Skip to content

refactor: structure cleanup, de-duplication & type-system tidy (no behavior change)#296

Open
sebastianwessel wants to merge 15 commits into
mainfrom
refactor/structure-cleanup
Open

refactor: structure cleanup, de-duplication & type-system tidy (no behavior change)#296
sebastianwessel wants to merge 15 commits into
mainfrom
refactor/structure-cleanup

Conversation

@sebastianwessel

Copy link
Copy Markdown
Contributor

What & why

First structure & cleanup phase of the refactor: file/folder structure, de-duplication, and a tidier type system. No functional behavior change, no dependency change — logic and behavior are preserved exactly. Baseline held at every commit: npm run build clean + 2619/2619 tests + lint.

Verification was gated on the full build (tsc), not just jest — ts-jest transpiles without full type-checking, so the build caught things tests didn't.

Commits (each independently green, reviewable)

Area Change
dead code delete unused issue/pattern/session.model.ts (~457 LOC); remove dead public-API-only types (FilePath, CodeLocation, Metrics, …)
types unify duplicated root-cause / extract-log types (one definition, forward-layered); split the 323-line shared/types/index.ts into domain-focused files behind a barrel (zero import churn); replace generic primitives.ts with purpose-named files
dedup centralize forge-integration contracts (QualOpsResult, comment marker, issue DTO) → src/shared/types/integrations.ts, previously copy-pasted in github/gitlab
structure introduce src/kernel/ for pure stdlib-only helpers; relocate the content-hash utility
constants extract CONFIDENCE_DISPLAY_THRESHOLDS and TOKENS_PER_MILLION (homed in un-mocked modules)
hygiene strip narration/redundant comments; rename the unclear forges/ concept to integrations

Net +359 / −884.

Explicitly out of scope (follow-ups)

  • The full 7-layer migration (moving all src/ into the target contracts/kernel/platform/llm/domains/… tree) — a mapped multi-PR effort.
  • Behaviorally-divergent "duplicates" (e.g. escapeHtml variants, retry policies, the 4 location parsers) — collapsing them would change behavior; left intact.
  • Five latent-bug findings surfaced during the work (report-root path guard, confidence-scale inconsistency, dead ERROR_LOG constant, GitLab redaction consistency, FrameworkContext duplicate) — tracked separately; they are behavior changes and depend on this landing first.

Public API note

The exported type surface shrank (unused types removed). The exported stage/config functions are unchanged. Fine for a 0.x line; noted in the changelog.

🤖 Generated with Claude Code

sebastianwessel and others added 14 commits July 9, 2026 13:42
Removes three fully-unused modules (~457 LOC) — verified no importers
outside their own barrel re-exports. Also removes the mismatched legacy
severity vocabulary (critical/error/warning/info) and category enum they
carried, which conflicted with the live critical/high/medium/low set.

No behavior change: build clean, 2619/2619 tests pass (unchanged).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
One definition per concept, forward-layered (shared/types is the home;
stages import from it — no low→high dependency introduced):
- RootCauseTaxonomy: delete the byte-identical copy in taxonomy.ts;
  re-export from shared/types.
- RootCauseClassification: delete the identical ClassificationResult
  interface in root-cause-extract; use the shared type.
- ExtractLog: single definition in shared/types (kept the index
  signature superset); extract-log.ts re-exports it.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…orges/core

QualOpsResult, the QUALOPS_COMMENT_MARKER constant, and the loosely-typed
forge issue shape were duplicated byte-for-byte in github-integration.ts and
gitlab-integration.ts. Centralized into a new src/forges/core module; both
integrations import from it. The forge issue DTO is renamed ForgeReviewIssue
to disambiguate it from the canonical ReviewIssue (it is a forge-boundary
type read from unvalidated JSON, deliberately kept distinct — not widened).

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Establishes src/kernel/ as the stdlib-only shared-utility layer (concept
architecture §2). Moves the content-hashing helper (calculateFileHash/
calculateFileHashes — only node:crypto + node:fs, genuinely pure) to
kernel/hash.ts; extract-log.ts imports it via the @/kernel alias. Test
mirror relocated to tests/unit/kernel/hash.spec.ts and repointed.

concurrency.ts was intentionally NOT moved: it depends on the logger, so
it is not stdlib-pure; relocating it would either seed a kernel→shared
dependency or require removing logging (a behavior change). Deferred.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The 323-line barrel mixed generic primitives, AI/provider config, framework
context, the core finding shapes, pipeline identity, and per-stage metadata
for five different stages. Split by domain/purpose with speaking names:

  primitives.ts · ai-config.ts · framework-context.ts · finding.ts ·
  pipeline.ts · analysis-metadata.ts · review-metadata.ts ·
  root-cause-metadata.ts · fix-metadata.ts · report-metadata.ts ·
  judge-metadata.ts

index.ts is now a pure barrel re-exporting them, so every existing
`from '.../shared/types'` import keeps resolving — zero consumer churn.
Type definitions are copied verbatim (no field renames — those would be a
behavior change on serialized shapes). The drifted second FrameworkContext
in framework-detector.ts is noted for a separate reconciliation.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
primitives.ts was a generic bucket holding three unrelated concerns. Split
into speaking names: metrics.ts (Metrics), source-code.ts (FilePath,
FileContent, CodeLocation, CodeSnippet), session.ts (SessionId). Barrel
re-exports them, so the package's public type API is unchanged (these types
are exported via src/index.ts for external consumers — they have no internal
callers, which is expected for public-API vocabulary).

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… constant

The 1-10 confidence display cutoffs (>=8 High, >=6 Medium) were hardcoded
identically in report/utils/formatters.ts and report/templates/components.ts.
Extracted to CONFIDENCE_DISPLAY_THRESHOLDS in a new report/constants.ts, with
a doc comment clarifying it is display-only bucketing, not a gating threshold.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
FilePath, SessionId, FileContent, CodeLocation, CodeSnippet, and Metrics were
exported via src/index.ts (`export * from './shared/types'`) but used NOWHERE
in src, tests, or evals — verified by whole-repo search. They were public API
by accident, not by design. Removed (deletes the metrics.ts/source-code.ts/
session.ts files added in the previous commit, now that a full-repo usage
check confirms they are unreferenced).

Reduces the published package's exported type surface — acceptable for a 0.x
package with no evidence of external use; flagged for release notes. Types
that ARE used (FrameworkContext, ReviewIssue, the metadata shapes, Config…)
are untouched.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The per-million token-pricing divisor (1_000_000) was hardcoded in 6 cost-math
sites across base.ts, bedrock.ts, and all-command.ts. Extracted to a named
constant in a dedicated src/ai/providers/pricing-constants.ts.

Homed in its own module (not config.ts) deliberately: several provider unit
tests mock '@/config/config' wholesale, which would make a constant defined
there `undefined` under mock (NaN cost). A dedicated, never-mocked file keeps
the real value everywhere. Distinct from the un-underscored 1000000
maxTokensPerFile cap, which is a different concept and left untouched.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Remove file-header and rationale comments that restated the obvious or
tracked history ("previously duplicated", "behaviour unchanged", etc.).
Code stays lean; names carry the meaning.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…argon)

src/forges/core/index.ts -> src/integrations/shared.ts; ForgeReviewIssue ->
IntegrationReviewIssue. Matches the term the specs already use for the
GitHub/GitLab integrations.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…s.ts

Shared code belongs under shared/; the top-level integrations/ name is
reserved for the later migration of the github/ and gitlab/ folders.

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…rations.ts

No behavior change: build clean, 2619/2619 tests pass, lint clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ypes

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jul 9, 2026

Copy link
Copy Markdown

QualOps Code Quality Analysis

Status: ⚠️ WARNINGS - Medium severity issues found

Summary

  • Total Issues: 1
  • Critical: 0 🔴
  • High: 0 🟠
  • Medium: 1 🟡
  • Low: 0 🟢
  • Files Analyzed: 28

🟡 Medium Issues (1)

  • src/shared/types/framework-context.ts:1 - maintainability
    Duplicate FrameworkContext interface: the new canonical shared/types/framework-context.ts has stricter types than the existing one in shared/utils/documentation-context.ts, creating two divergent definitions

📊 Full Report

View detailed report


Powered by QualOps

…eanup

# Conflicts:
#	src/shared/types/pattern.model.ts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant